/**
 * @p.md
 * 
 * Context 提供 Actor 交互的上下文
 */
import { PID } from './pid';
import { Actor } from './actor';
import { ActorSystem } from './actorSystem';
import { Props } from './props';
import { Future } from './future';

/**
 * Context 接口，包含 Actor 上下文的所有功能
 */
export interface Context extends
  InfoPart,
  BasePart,
  MessagePart,
  SenderPart,
  ReceiverPart,
  SpawnerPart,
  StopperPart {
}

/**
 * 包含 Actor 上下文基本信息的接口
 */
export interface InfoPart {
  /**
   * 获取当前 Actor 的父 Actor
   */
  parent(): PID | null;
  
  /**
   * 获取当前 Actor 的 PID
   */
  self(): PID;
  
  /**
   * 获取当前关联的 Actor 实例
   */
  actor(): Actor;
  
  /**
   * 获取所属的 Actor 系统
   */
  actorSystem(): ActorSystem;
}

/**
 * 包含 Actor 上下文基本功能的接口
 */
export interface BasePart {
  /**
   * 获取当前接收超时设置
   */
  receiveTimeout(): number;
  
  /**
   * 获取当前 Actor 的子 Actor 列表
   */
  children(): PID[];
  
  /**
   * 回复当前消息的发送者
   * @param response 回复的消息
   */
  respond(response: any): void;
  
  /**
   * 将当前消息存入暂存区
   */
  stash(): void;
  
  /**
   * 监视指定的 Actor
   * @param pid 要监视的 Actor 的 PID
   */
  watch(pid: PID): void;
  
  /**
   * 取消监视指定的 Actor
   * @param pid 要取消监视的 Actor 的 PID
   */
  unwatch(pid: PID): void;
  
  /**
   * 设置接收超时时间
   * @param duration 超时时间（毫秒），小于 1 毫秒将禁用超时
   */
  setReceiveTimeout(duration: number): void;
  
  /**
   * 取消接收超时设置
   */
  cancelReceiveTimeout(): void;
  
  /**
   * 将当前消息转发给指定的 Actor
   * @param pid 目标 Actor 的 PID
   */
  forward(pid: PID): void;
  
  /**
   * 在 Future 完成后重新进入 Actor 处理
   * @param future 等待的 Future
   * @param continuation 完成后的回调函数
   */
  reenterAfter(future: Future<any>, continuation: (result: any, error: Error | null) => void): void;
}

/**
 * 包含消息处理相关功能的接口
 */
export interface MessagePart {
  /**
   * 获取当前处理的消息
   */
  message(): any;
}

/**
 * 包含消息发送相关功能的接口
 */
export interface SenderPart {
  /**
   * 发送消息给指定的 Actor
   * @param target 目标 Actor 的 PID
   * @param message 要发送的消息
   */
  send(target: PID, message: any): void;
  
  /**
   * 发送请求给指定的 Actor，期望得到响应
   * @param target 目标 Actor 的 PID
   * @param message 要发送的消息
   */
  request(target: PID, message: any): void;
  
  /**
   * 发送请求给指定的 Actor，并返回一个 Future 对象以获取响应
   * @param target 目标 Actor 的 PID
   * @param message 要发送的消息
   * @param timeout 超时时间（毫秒）
   */
  requestFuture(target: PID, message: any, timeout: number): Future<any>;
}

/**
 * 包含消息接收相关功能的接口
 */
export interface ReceiverPart {
  /**
   * 获取当前消息的发送者
   */
  sender(): PID | undefined;
}

/**
 * 包含 Actor 创建相关功能的接口
 */
export interface SpawnerPart {
  /**
   * 创建一个新的 Actor
   * @param props Actor 属性
   */
  spawn(props: Props): PID;
  
  /**
   * 创建一个指定名称的新 Actor
   * @param props Actor 属性
   * @param name 新 Actor 的名称
   */
  spawnNamed(props: Props, name: string): PID;
  
  /**
   * 创建一个带有前缀的新 Actor
   * @param props Actor 属性
   * @param prefix 名称前缀
   */
  spawnPrefix(props: Props, prefix: string): PID;
}

/**
 * 包含 Actor 停止相关功能的接口
 */
export interface StopperPart {
  /**
   * 停止指定的 Actor
   * @param pid 要停止的 Actor 的 PID
   */
  stop(pid: PID): void;
} 